home *** CD-ROM | disk | FTP | other *** search
/ JCSM Shareware Collection 1993 November / JCSM Shareware Collection - 1993-11.iso / cl720 / qbnws31j.lzh / XMS.REF < prev    next >
Text File  |  1992-02-01  |  15KB  |  320 lines
  1.     
  2.                                    XMS.ASM
  3.                     Extended Memory Driver for QuickBASIC 4.0+
  4.     
  5.                      (C) 1992 by Sequential Software, Inc.
  6.                                  P.O. Box 53
  7.                             Somerset, KY 42402-0053
  8.                               BBS: (606) 561-5766
  9.                               Author: Robin Duffy
  10.     
  11.          Now you can use extended memory (if available) from your
  12.     QuickBASIC programs with just a few simple calls. This package
  13.     provides a rudimentry interface to HIMEM.SYS for QuickBASIC 4.0+ and
  14.     BASCOM 6. Routines are provided to initialize, allocate, release, and
  15.     otherwise manipulate XMS memory directly from your program.
  16.     
  17.          My personal thanks go to Ethan Winer. The overall concept of an
  18.     interface for XMS memory was inspired by his method of interfacing
  19.     expanded memory with QuickBASIC. Without his brilliant work I would
  20.     have never thought to set this up as an integrated package.
  21.     
  22.      REQUIREMENTS:
  23.     
  24.          1. Requires a 80286 or better processor that has extended
  25.             memory available (goes without saying).
  26.     
  27.          2. Requires HIMEM.SYS to be loaded via CONFIG.SYS.  These
  28.             routines will work with extended memory managers that adhere
  29.             to the Lotus/Intel/Microsoft/AST eXtended Memory Specification
  30.             (XMS) version 2.0 or greater and will not work with other
  31.             extended memory managers.
  32.     
  33.          3. Requires DOS 3.0 or greater. This is a requirement of HIMEM
  34.             and not of this software. These routines may be called with
  35.             any DOS version, but will only work if HIMEM is loaded.
  36.     
  37.     INSTALLATION: 
  38.     
  39.          The XMS driver is provided as an object file ready for inclusion
  40.     in your favorite library. You will need LIB.EXE and LINK.EXE to create
  41.     linking and Quick libraries. To add XMS.OBJ to your library you can
  42.     use the following command: 
  43.     
  44.               LIB  mylib +xms; 
  45.     where mylib is the name of your present linking library. If you do not
  46.     use special libraries, use the default library QB.LIB.  
  47.     
  48.          Next create a Quick library for use in the editing environment
  49.     with LINK.EXE like this: 
  50.     
  51.               LINK /q/se:256 mylib.lib xms,,nul,bqlb40 
  52.  
  53.     If you are using QB 4.5, substitute BQLB45 for bqlb40.
  54.     
  55.          XMS is now ready for use. Start the QB environment with the /L
  56.     switch and the name of your Quick library to make it available inside
  57.     the QB editor.  
  58.     
  59.     GENERAL NOTES:
  60.     
  61.          1. This code will work in the QB environment. However, you must
  62.             explicitly release the memory you have allocated from your
  63.             program BEFORE IT ENDS. QB will NOT release it when it exits!
  64.             You may otherwise set breakpoints, trace, etc. without any
  65.             problems. Do not make edits that require program restarts or
  66.             the memory will be lost until the next reboot.
  67.     
  68.          2. Remember that if XMSError shows an error, any subsequent
  69.             successful operation will reset it to zero. See XMSError
  70.             later in this text for more info.
  71.  
  72.          3. Writes and reads from extended memory take a little longer
  73.             than accesses to conventional memory. This is not a fault
  74.             of this software. Rather, it takes time for HIMEM.SYS to
  75.             switch the processor in and out of protected mode. However,
  76.             these extended accesses are still hundreds of times faster
  77.             than disk accesses.
  78.     
  79.          4. All these routines may be safely called on any machine even if
  80.             it has no extended memory.  They all reference a flag set by
  81.             InitXMS, and just return if no memory is available.  This
  82.             greatly simplifies the effort required to use this stuff.
  83.     
  84.          In the spirit of programmer to programmer, I am not requiring any
  85.     compensation for the use of these routines. You may use them as you
  86.     see fit. However, since these routines are free, I will not be held
  87.     responsible for any damages resulting from use of these routines.
  88.     Likewise I do not guarrantee the accuracy of any information provided
  89.     here. It would be a nice gesture if you mention where you got this in
  90.     your program source code.
  91.     
  92.          Below is a reference for the routines supported by this driver.
  93.     Although crude at this point, the routines still provide a very usable
  94.     and convenient interface for extended memory. Unless otherwise noted,
  95.     all parameters are integers.
  96.     
  97.     ----------------------------------------------------------------------
  98.     INITXMS: Basic sub
  99.     
  100.          This routine must be called prior to any others in this driver
  101.     for extended memory to be available for your program.
  102.     
  103.          CALL InitXMS(There%, MemSize%)
  104.     
  105.          There% - on exit will contain a -1 (XMS is good) or a zero (XMS
  106.                   not installed or unavailable).
  107.     
  108.          MemSize% - if There% is -1, this will contain the amount of
  109.                   extended memory available (in K bytes) for your use.
  110.                   This will probably be less than the machine total
  111.     ---------------------------------------------------------------------
  112.     XMSERROR: Basic function
  113.     
  114.          This function returns the success of the last XMS operation. You
  115.     may test the success of any operation right afterward by referencing
  116.     this function.  Because it is a function, it must be declared before
  117.     it may be used.
  118.     
  119.          DECLARE FUNCTION XMSError%()
  120.     
  121.          Status% = XMSError%
  122.     
  123.          Status%  -  0 = last operation sucessful
  124.                     -1 = last operation resulted in error
  125.     
  126.          You can test this function after every routine except for
  127.     InitXMS. It should be noted that any sucessful operation after the
  128.     operation causing the error will clear this function. If extended
  129.     memory is not available (for whatever reason), this function will
  130.     always return an error condition (because XMS memory is not there).
  131.     
  132.          See also WhichXError, which returns the actual error code, and
  133.     the table of error codes at the end of this text.
  134.     ---------------------------------------------------------------------
  135.     GETXMS: Basic function
  136.     
  137.          This function allocates an extended memory block for your use and
  138.     returns a handle (much like DOS file handles) used for all future
  139.     references to this block. Your program can use multiple blocks.
  140.     Because it is a function, it must be declared before it may be used.
  141.     
  142.          DECLARE FUNCTION GetXMS%(Amount%)
  143.     
  144.          Handle% = GetXMS(Amount%)
  145.     
  146.     Where:
  147.          Handle% - returns the block handle. 0 means error in allocation.
  148.     
  149.          Amount% - On entry, set this to the size block desired (in K
  150.                    bytes).
  151.     ---------------------------------------------------------------------
  152.     FREEXMS: Basic sub
  153.     
  154.          This sub will release memory allocated by GetXMS.
  155.     
  156.          CALL FreeXMS(Handle%)
  157.     
  158.          where Handle% is the block handle assigned by GetXMS. It is
  159.     important to release any memory you allocate prior to exiting your
  160.     program. This memory is not automatically released by DOS at
  161.     termination as is conventional memory, but instead remains allocated.
  162.     Failure to deallocate XMS memory will cause it to be "lost" until the
  163.     next time the host machine is rebooted.
  164.     ---------------------------------------------------------------------
  165.     ARRAY2XMS: Basic sub
  166.     
  167.          This sub will copy a block from conventional far memory to an
  168.     allocated block of XMS memory. This block may be all or part of an
  169.     integer, long integer, or user type array. Using the optional long
  170.     syntax you may save any continuous portion of convential memory to
  171.     XMS, including the screen!
  172.     
  173.         CALL Array2XMS(SEG Array%(Start%), Handle%, NumBytes&)
  174.                               or
  175.         CALL Array2XMS(BYVAL FromSeg%, BYVAL FromOff%, Handle%, NumBytes&)
  176.     
  177.     Where:
  178.          Array%(Start%) - Start of conventional memory block to transfer
  179.     
  180.          Handle% - Handle assigned by GetXMS
  181.     
  182.          NumBytes& - long integer specifying the number of bytes to
  183.               transfer.  If a constant is used, it should be appended
  184.               by a "&" specifier (forcing a long reference).
  185.     
  186.          Optionally, you can pass the starting segment and offset of the
  187.     source block by using the BYVAL keyword.
  188.     ---------------------------------------------------------------------
  189.     XMS2ARRAY: Basic sub
  190.     
  191.          This sub will copy a previously saved block from extended memory
  192.     to a block in conventional memory. This is the compliment to Array2XMS.
  193.     
  194.          CALL XMS2Array(Handle%, SEG Array%(Start%), NumBytes&)
  195.                              or
  196.          CALL XMS2Array(Handle%, BYVAL ToSeg%, BYVAL ToOff%, NumBytes&)
  197.     
  198.     Where:
  199.          Handle% - handle of XMS block of stored data
  200.     
  201.          Array(Start%) - start of destination block in normal memory.
  202.     
  203.          NumBytes&  - long integer specifying the number of bytes to
  204.               transfer. If a constant is used, it should be appended
  205.               by a "&" specifier (forcing a long reference).
  206.     
  207.          Optionally, you can pass the starting segment and offset of the
  208.     destination block by using the BYVAL keyword.
  209.     ---------------------------------------------------------------------
  210.     XGETELEMENT: Basic sub
  211.     
  212.           This sub will return a portion of a block of XMS memory into a
  213.           variable. This is handy for retrieving a single value from a
  214.           saved block of XMS.
  215.     
  216.         CALL XGetElement(Handle%, Variable, EleLen%, EleNum%)
  217.     
  218.     Where:
  219.         Handle% - Handle assigned to XMS block by GetXMS
  220.     
  221.         Variable - Variable to receive the returned value. This variable
  222.               can be any type of variable except a conventional string.
  223.     
  224.         EleLen% - Integer describing the length of the elements stored in
  225.               in the XMS block. This value must be an even number. Thus,
  226.               integers would be 2, long integers are 4, etc. You may
  227.               specify any length, but it is assumed all elements stored
  228.               in the block are the same length.
  229.     
  230.         EleNum% - the element number to retrieve. This value is used
  231.               with EleLen% to determine the offset into the XMS block
  232.               to start reading. The first element is considered to be
  233.               element number one, not zero.
  234.     
  235.           Variable types supported are integers, long integers, single and
  236.     double precision numbers, and user type variables AS LONG AS THE LENGTH
  237.     OF THE VARIABLE IS EVEN. This variable cannot be a conventional string.
  238.     If the variable length is odd it will be forced even without error.
  239.     ---------------------------------------------------------------------
  240.     XSETELEMENT: Basic sub
  241.     
  242.          This is the compliment procedure for GETELEMENT. The syntax is
  243.     identical to XGETELEMENT, except that Variable holds the value to
  244.     place into XMS. All restrictions and notes for XGETELEMENT apply to
  245.     this procedure.
  246.     ---------------------------------------------------------------------
  247.     WHICHXERROR: Basic function
  248.     
  249.          This function returns the actual error code as supplied by
  250.     HIMEM.SYS (see notes on XMSError). Where XMSError provides an easy
  251.     check for errors, this procedure gives you the actual error code.
  252.     Because it is a function, it must be declared before it may be used.
  253.     
  254.          DECLARE FUNCTION WhichXError%()
  255.     
  256.          Code% = WhichXError%
  257.     
  258.          Code% receives the actual error code generated by HIMEM.SYS. If
  259.     XMS memory is unavailable for any reason, this function will always
  260.     return error 128 - "Function not supported".
  261.     ---------------------------------------------------------------------
  262.     SETXERROR: Basic sub
  263.     
  264.          This sub will set the error value returned by WhichXError.
  265.     
  266.          CALL SetXError(ErrorCode%)
  267.     
  268.          where ErrorCode% is the value to set.
  269.     
  270.          This sub is handy for many purposes, among those being
  271.     communications between modules and procedures. For example, if you
  272.     decide to use XMS memory as an array (using the XGET and XSETELEMENT
  273.     procedures), you can set an illegal element code if user input is out
  274.     of bounds.
  275.  
  276.          The value you specify should be in the range of 0 - 255. If the
  277.     value is greater than 255, only the low byte of the value passed will
  278.     be used.
  279.     
  280.          Please note this sub will not work if XMS is not available. This
  281.     is to avoid confusion on the part of WhichXError. WhichXError will
  282.     always return a "Function not supported" error if XMS is not present.
  283.     ---------------------------------------------------------------------
  284.                             ERROR CODES RETURNED
  285.     
  286.          The error codes returned by this driver are the actual HIMEM.SYS
  287.     error codes, so not all will apply to this package. In the spirit of
  288.     completeness I shall include all codes I have documentation on. The
  289.     driver takes no action upon errors beyond reporting their occurrence.
  290.     This is left up for you to handle.
  291.     
  292.     128  Function not supported
  293.     129  VDisk was detected
  294.     130  An A20 error occurred
  295.     142  General driver error (HIMEM.SYS)
  296.     143  Fatal driver error (HIMEM.SYS)
  297.     144  HMA does not exist
  298.     145  HMA is already in use
  299.     147  HMA is not allocated
  300.     148  A20 still enabled
  301.     160  Not enough memory
  302.     161  All handles are allocated
  303.     162  Invalid handle
  304.     163  Source handle invalid
  305.     164  Source offset is invalid
  306.     165  Destination handle is invalid
  307.     166  Destination offset is invalid
  308.     167  Invalid length parameter
  309.     168  Move has invalid overlap
  310.     169  Parity error occurred
  311.     170  Block is not locked
  312.     171  Block is locked
  313.     172  Block lock count overflow
  314.     173  Lock failed
  315.     176  Only a smaller UMB is available
  316.     177  No UMB's are available
  317.     178  UMB segment is invalid
  318.         
  319.                               ** End of documentation **
  320.